Added documentation section

diff --git a/gpsbabel/README.contrib b/gpsbabel/README.contrib
index 15a1ef24c483df5b4dc263be9affe2e10f543fc6..b2f6182860c438cf5ead9957a1d4b57bcc58279f 100644 (file)
--- a/gpsbabel/README.contrib
+++ b/gpsbabel/README.contrib
@@ -2,6 +2,9 @@ If you're interested in contributing to this program, here are some
 guidelines.  Mail patches to gpsbabel-code@lists.sourceforge.net for
 consideration and integration.
 
+Rules to Live By
+----------------
+
 Standards are good.   ISO C and POSIX are greatly preferred.
 
 Reuse is good, if doing so is not onerous.  For example, using the expat
@@ -12,6 +15,15 @@ require expat.
 You may find format_skeleton.c and filter_skeleton.c in the source tree
 to be helpful examples. Just add meat!
 
+Compilers complain for a reason.   Code shouldn't emit warnings.
+
+The entire world doesn't run <your OS here>.  I've tested this code on
+at least five different OSes.  If you find yourself wanting to insert
+compiler or OS specific magic, please resist.
+
+Submitting Patches
+------------------
+
 If you are creating a new target you should submit patches (use 
 "cvs diff -uN" to create patches) to the following files:
 * Yourcode.c and/or Yourcode.h - this is the code required to do your
@@ -20,22 +32,59 @@ If you are creating a new target you should submit patches (use
   GPSBabel.
 * Makefile - an updated Makefile telling the compiler how to build and link
   your conversion into GPSBabel
-* README - an excerpt for the README about your conversion and any  
-  idiosyncrasies  it may have.
 * testo - an updated script that tests your conversion (this should produce
   no output if all is good, see the current testo script for examples)
 * YourOutput - a sample file of code produced by your function (used in testo
   and lives in a directory called "reference").
+* Documentation - see below.
 
 Please ensure that you are building and testing against the latest code
 from the top of the CVS tree and that any code you modify is the latest
 version from the CVS - Note: code changes sometimes occur frequently!
 
-Compilers complain for a reason.   Code shouldn't emit warnings.
+Documentation
+-------------
+
+HTML and text documentation are generated automatically from DocBook 
+source located in the "xmldoc" directory.  That directory contains 
+two subdirectories of interest: "formats" and "filters".  If your
+contribution adds or affects a format, you'll want to be in the "formats"
+directory.  Otherwise, you'll want to be in the "filters" directory.
+
+You should contribute a file called "yourname.xml", where "yourname" is the
+name you would give on the command-line to invoke your new format or filter.  
+For example, the arc filter is documented in "filters/arc.xml".
+
+This file contains a general description of your format or filter, any 
+limitations in your support for it, and anything else the end user should 
+know.  For file formats, links to manufacturers' websites are encouraged.  
+The contents of this file are not valid or even well-formed XML on their own; 
+they are included into a larger framework.  If you know DocBook, you should 
+ensure that the contents of this file will validate if included in a <section>.
+If you do not know DocBook, see the other files in this directory for examples 
+or see http://docbook.org/tdg/en/html/docbook.html for the gory details.  Tags 
+of interest will almost certainly include <para> for paragraphs, 
+<ulink url="..."> for web links, and <screen format="linespecific"> for 
+example command lines.
+
+For each option supported by your format or filter, you should also contribute
+a file in the "options" subdirectory called "yourname-youroption.xml", again
+using the names you would use on the command line to invoke your format or 
+filter with that particular option.  For example, the "distance" option to the
+"arc" filter is documented in "filters/options/arc-distance.xml".  These 
+files are similar to the general description above, and should meet the same
+validation requirements.
+
+As of this writing, there are two formats that violate this rule: Magellan 
+serial and Microsoft Streets & Trips.  Because those formats have the same
+names as other formats, their descriptions are located in "magellan1.xml" and
+"msroute1.xml" respectively.  These are special cases, and you should do your
+best to ensure that they remain the only special cases.
+
+Note that the automated framework already includes the name and description of
+your format and its options as described in vecs.c and yourcode.c, so there is
+no need to repeat that information in your documentation.
 
-The entire world doesn't run <your OS here>.  I've tested this code on
-at least five different OSes.  If you find yourself wanting to insert
-compiler or OS specific magic, please resist.
 
 Enjoy!